-*-Setx-*-


# Filters Tutorial
==================

This is a tutorial that demonstrates the "Filters" menu.  

In order to use it, you must first activate the menu by going to the menu
item "Alpha --> Global Setup --> Menus" and selecting 'Filters Menu' by
checking the corresponding checkbox.

The Filters Menu allows you to do successive "Search And Replace" operations.
All the operations are gathered in files called "filters" which you can 
apply to any text file opened in Alpha.

This Tutorial, when opened as a sandbox (for instance from the Filters
Sandbox command in the Filters Utilities submenu), is a "shell" window.
None of the changes you make will affect the actual file. If you close the
window and then open it as a sandbox again, you will start with the same
example as before.

This tutorial is in Setx mode to take advantage of some file marking and
colorizing procedures. The Filters menu can work in any mode.


# Filter Examples
=================


# First example
---------------

Suppose your file is full of accented letters and you want to strip all the
accents (to send an e-mail for instance).  You can select the filter called
"Strip The Accents".  Once it is selected, you will see its name at the
bottom of the Filters menu.  Bring your current file's window to the front
and choose the "Apply Filter To Window" menu item.

Alternatively you can use the following key binding: press control-F,
release, then hit the W key.  If you convert only a selected region, press
control-F, release, then hit the S key.  To pick a filter you can also use
control-F P (try it!).

Experiment with the following sample, full of accented letters (this a
french poem by Apollinaire. We want accented letters, don't we) :

    S'étendant sur les côtés du cimetière 
    La maison des morts l'encadrait comme un cloître 
    À l'intérieur de ses vitrines 
    Pareilles à celles des boutiques de modes 
    Au lieu de rire debout 
    Les mannequins grimaçaient pour l'éternité.


# Second example
----------------

Suppose no filter suits your needs. You'll have to write your own. This is
very easy. Choose the "New Filter" menu item in the "Filters Utilities"
submenu. You'll be prompted for a name to give to the new filter. Let's
call it "MyNewFilter": this new filter is now the active filter.

Suppose you want to change in a text all the occurences of J.S. Bach in L.
van Beethoven, then to delete all the occurences of the § character and
finally to replace multiple tabulations by a single one. You have to copy
and paste the three following lines in your filter :

J.S. Bach	L. van Beethoven
§
\t+	\t	1

The arguments are tab-separated (more about the filters syntax later). Now
save your filter and apply it as in the preceding example. You can check
the syntax of your new filter thanks to the "Check Syntax" menu item in the
Filters Utilities submenu (or hit control-F Y).

Experiment on the following example :

    Works by J.S. Bach :
    §		for organ
    §		for cello


# Third example 
---------------

Suppose you want to apply several filters successively: for instance the
fileter "Html To Accents" then the filter "Accents To Rtf". This can be
done in one run thanks to the MultiFilter. The MultiFilter will be the list
of filters you want to apply (in the order you want them to be applied). To
build such a list, hold the Shift key down then open the Filters Utilities
submenu: instead of "New Filter", the first item will now be "New Multi
Filter" which brings a selection dialog. The dialog contains a popup menu
with a list of all the currently available filters. Choose the filters you
want in this popup menu and press the "Add" button to add them to the editing
field. To apply the Multifilter to a selection, a file or a folder, hold
down the Shift key and select the corresponding item in the Filters menu.
 
To experiment, take the follawing example containing a series of accented
letters a la LaTex, and build a multifilter with the "Latex To Accents"
filter followed by the "Strip The Accents" filter:

    \`{a}\`{u}\'{e}\`{e}\^{o}\^{\i}\^{e}\^{a}


# Fourth example
----------------

If you want to do temporary conversions on the fly and do not want to keep
them in a filter, you have the Temporary Filter. You use it exactly like
any other filter. The only difference is that the instructions you write in
it will not be saved. They will remain only as long as you do not quit
Alpha and do not close the Temporary Filter.

Exercise : in the present file, replace all the occurences of the isolated
word filter by FILTER and all the double quotes by single quotes.

Solution : open a temporary filter and type the following two lines :

filter	FILTER	1im
"	'

Then save and choose the 'Apply Temp To Window' menu item.


# More examples
---------------

Choose the menu item "Filters --> Filter Utilities --> Edit A Filter" and
choose the filter named 'Example'. Most of the filters provided with the
Filters Menu deal with accents conversions but you can imagine many kinds
of conversions.

A more advanced example is given in the "Convert Html To Latex" filter
which attempts to convert an Html document to a latex source file ready to
process with LaTeX. 

Experiment with the following example :

    <HTML>
    <HEAD>
       <TITLE>THE ALPHA TEXT EDITOR</TITLE>
       <META NAME=GENERATOR CONTENT="Html Maker 1.0">
       <X-SAS-WINDOW TOP=42 BOTTOM=757 LEFT=4 RIGHT=534>
    </HEAD>
    <BODY>
    <H3>WELCOME TO ALPHA</H3>
    <P>&nbsp;</P>
    <H4>Introduction</H4>
    <P>Alpha is a<I> very powerful, </I>multi-purpose text editor. Alpha
    is <I>multi-modal,</I> which means it switches between different
    modes depending on which type of document you are editing.</P>
    <H4>Tutorial</H4>
    <P>Here is a list of various modes available in Alpha :</P>
    <UL>
       <LI>tcl
       <LI>html
       <LI>tex
       <LI>java
       <LI>perl
    </UL>
    </BODY>
    </HTML>



# Filters Key Bindings
======================

There are a few easy to remember keybindings "à la emacs".  For all of them
you have to press 'ctrl-f', release, then hit one of the following letters:
	-  p  to <p>ick a filter
	-  s  to filter the <s>election
	-  w  to filter the current <w>indow
	-  d  to filter a <d>irectory
	-  n  to create a <n>ew filter
	-  e  to <e>dit a filter
	-  t  to display the <t>emporary filter
	-  c  to edit the <c>urrent filter
   
There are many others. Press 'ctrl-F B' (or select Display Bindings in the 
Filters Utilities submenu) to see all the available bindings.

# End of Tutorial.

